home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / tex / cawf404.zip / 00readme < prev    next >
Text File  |  1993-12-07  |  12KB  |  309 lines
  1. Cawf - nroff-like text formatter
  2.  
  3. Cawf is a C version of awf, Henry Spencer's Amazingly Workable (text)
  4. Formatter.  (Awf is written in awk and appears in comp.sources.unix,
  5. Volume 23, Issue 27.)  Cawf and awf provide a usable subset of raw nroff
  6. capabilities and the styles of the man(7), me(7) and ms(7) macro sets.
  7. One of cawf's virtues is that it will run on PC clones under MS-DOS.  It
  8. is also, like awf, totally independent of any licensed Unix source code.
  9. Another cawf virtue is that it supports more nroff functions and one more
  10. macro style -- ME -- than awf.
  11.  
  12. This distribution contains complete source, make files for Unix and
  13. MS-DOS, documentation (raw and formatted) and MS-DOS executables for cawf
  14. and a companion output filters, bsfilt.
  15.  
  16. This is distribution of cawf, version 4.04.  Changes include:
  17.  
  18.     *  Some rudimentary output device support has been added, via a device
  19.        configuration file.
  20.  
  21.     *  The code has been converted to use unsigned characters.
  22.  
  23.     *  An attempt has been made to make the code ANSI C compliant.
  24.  
  25.     *  The following bugs have been fixed:
  26.  
  27.         A bug in the locating of the device file has been corrected,
  28.         so that the code performs as documented.
  29.  
  30.         Null macro arguments are ignored.
  31.  
  32.         Some unused arguments to local functions have been more
  33.         carefully type cast to avoid portability problems.
  34.  
  35.     *  The .fl and .rn requests are now supported.
  36.  
  37.     *  Limited support has been added for the non-break request control
  38.        character, the acute accent (').
  39.  
  40.     *  Argument count conditionals -- operating on \n(.$ -- may now use
  41.        the >= and <= operators in addition to [<=>].
  42.  
  43.     *  Macros may be terminated with "..", ".", "''" or "'".
  44.  
  45.     *  String interpolation is performed if it is specified at the start
  46.        of the defined value -- i.e., the string value may be a request
  47.        for interpolation of another string.
  48.  
  49.     *  In .ds string values "\\b" is converted to '\b' and "\\\\"" is
  50.        converted to '\\'.  No other sequence, beginning with '\\', is
  51.        modified.
  52.  
  53.     *  The .tr request has been enhanced to handle named characters and
  54.        string interpolation.
  55.  
  56.     *  The SS macro is now included in man.mac.
  57.  
  58.     *  The cawf version number is now displayed in the help output.
  59.  
  60.     *  A limited -me macro set is included in me.mac.
  61.  
  62.     *  Some forms of the hyphen -- e.g., one of two `-' characters at
  63.        the start of a word or ME(7)'s \*- -- will now be output in bold
  64.        or italic face, if they're in effect.  See cawf(1) for a complete
  65.        description of the rules of hyphenation and the output of hyphen
  66.        characters.
  67.  
  68.        A bug was corrected in the handling of the \*(em hyphen.
  69.  
  70.     *  Three part titles -- the .tl and .lt commands -- are now supported.
  71.  
  72.     *  4.02 handles TABs better.
  73.  
  74.     *  4.03 handles NULL characters in font and device definitions
  75.        properly.
  76.  
  77.     *  4.04 changes include:
  78.  
  79.        o  The -n<starting_page_number> and -o<page_number_range> options
  80.           are supported.
  81.  
  82.        o  The current date is preset in the ME td string or the
  83.           MS DY string.
  84.  
  85.        o  The MS CH string is preset to "- % -" and the CH string
  86.           is preset to \*(DY.
  87.  
  88.        o  Some minor bug fixes were made.
  89.  
  90.           .  The binary search in the Nreq() function in nreq.c is
  91.          now constrained to the proper length.
  92.  
  93.           .  Null strings -- e.g., defined with ".ds xx" -- are
  94.          now handled correctly.
  95.  
  96.  
  97. CONTENTS
  98. --------
  99.  
  100. This Unix distribution of cawf includes:
  101.  
  102.     00readme    this file
  103.     00diffs        description of differences between cawf and [nt]roff
  104.     *.c and *.h    source files to build cawf and bsfilt (bsfilt
  105.             removes Backspaces from cawf output)
  106.     bsfilt.1    nroff source for the bsfilt manual page
  107.     bsfilt.exe    bsfilt executable for MS-DOS
  108.     bsfilt.mak    MS-DOS Quick-C make file for bsfilt
  109.     cawf.1        nroff source for the cawf manual page
  110.     cawf.exe    cawf executable for MS-DOS
  111.     cawf.mak    MS-DOS Quick-C make file for cawf
  112.     common        initialization file for CAWFLIB library
  113.     device.cf    output device configuration file for CAWFLIB library
  114.     dumb.dev    device description file for CAWFLIB library
  115.     Makefile    Unix-style make file
  116.     man.mac        man(7) macros for CAWFLIB library
  117.     me.mac        me(7) macros for CAWFLIB library
  118.     ms.mac        ms(7) macros for CAWFLIB library
  119.     strcasecmp.c    the strcasecmp() function from BSD4.3 (See the
  120.             discussion under STRCASECMP for information on when
  121.             you might need to use this.)
  122.  
  123.  
  124.  
  125. LIBRARY
  126. -------
  127.  
  128. To use cawf, you must select a location for the CAWFLIB library files.  The
  129. distributed cawf.exe expects to find them in c:\sys\lib\cawf, but you can
  130. alter that with the CAWFLIB environment variable, or you can change the
  131. CAWFLIB #define in cawf.h and rebuild cawf from the sources.
  132.  
  133. CAWFLIB contains a minimum of six files:
  134.  
  135.     common        common raw nroff commands to get cawf started
  136.     dumb.dev    a set of character definitions for a plain, "dumb"
  137.             ASCII device - e. g., the console display, a CRT or
  138.             a basic line printer
  139.     device.cf    the output device configuration file
  140.     man.mac        the man(7) macros
  141.     me.mac        the me(7) macros
  142.     ms.mac        the ms(7) macros
  143.  
  144. You may want to add your own macro files to the library.  Just name them
  145. "m[your-name].mac", following the usual nroff naming convention for macro
  146. files.
  147.  
  148. If you have fancy output devices with special character specifications, you
  149. may want to generate new *.dev files for them.  Follow the format of dumb.dev
  150. in making new character specifications.  To define characters for a new
  151. device, select a name prefix for it and create a file in CAWFLIB with the
  152. name "<prefix>.dev".  To use the new file, set the TERM environment variable
  153. to <prefix> - e. g., when I test cawf on Unix, I need a vt100.dev, because
  154. my TERM environment variable value is usually vt100.  All I do is make
  155. vt100.dev a symbolic link to dumb.dev.  Even that isn't even necessary,
  156. because cawf will use dumb.dev if it can't find TERM.dev.
  157.  
  158. In addition to the character specifications possible through the *.dev files,
  159. cawf provides one-time font selection and bold or italic face support for
  160. output devices via its -d and -f options.  Cawf can be directed to issue
  161. specific device codes for bold and italic characters, and one font can be
  162. specified for the entire document.  Cawf has some built-in output device
  163. support, and addition support is contained in the device configuration file,
  164. device.cf.  Additional devices may be defined in device.cf.
  165.  
  166. It is not necessary to generate a new *.dev file for each output device
  167. definition.  Only when you need special character definitions do you need to
  168. create a *.dev file.  The dumb.dev file is adequate for most devices you 
  169. define in device.cf.
  170.  
  171.  
  172. SOURCES
  173. -------
  174.  
  175. A Unix make file and a cawf.mak file for version 2.5 of Microsoft MS-DOS
  176. Quick-C are included.  The Unix make file has some definitions that help
  177. tune it to the local Unix environment:
  178.  
  179.     CAWFLIB        is a string that can be used in lieu of changes
  180.             to cawf.h's CWFLIB #define.
  181.  
  182.     MALLOCH        is a string that should be defined when a UNIX
  183.             environment has a <malloc.h>, unless it also has a
  184.             <stdlib.h> with prototypes for malloc() and its
  185.             relatives.  In the latter case, you should define
  186.             STDLIB, but you don't need to define MALLOCH.
  187.  
  188.     STDLIB        indicates that standard library function prototype
  189.             definitions may be found in <stdlib.h>.
  190.  
  191.             STDLIB must be defined for MS-DOS Quick C.
  192.  
  193.             If STDLIB is not defined, the cawf sources try to
  194.             define their own library function return values.
  195.  
  196.     __STR__        The definition of this string must be deleted when
  197.             using the xlc 1.2 compiler on the RISC/System 6000
  198.             under AIX 3.2.  Put
  199.  
  200.                 -U__STR__
  201.  
  202.             in the Makefile DEFS string.  This must be done
  203.             because the xlc 1.2 compiler does not correctly inline
  204.             string functions when compiling pass3.c.
  205.  
  206.     UNIX        switches the build environment to Unix.  You may also
  207.             have to decide about MALLOCH, STDLIB, __STR__ and USG
  208.             when you define UNIX.
  209.  
  210.             Do not define UNIX for MS-DOS Quick-C; do define
  211.             STDLIB.
  212.  
  213.     USG        adjusts for System V.  (UNIX must also be defined.)
  214.  
  215.             You may also need to define USG to select